///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.helpers
{

import summit.basecamp.constants.BasecampOperation;
import summit.basecamp.constants.BasecampResource;
import summit.net.BasecampRequest;
import flash.net.URLRequestMethod;

/**
 * Helpers for Basecamp message (aka post) operations.
 */
public class MessageHelper
{
	private static const PATH_HELPER:String = "/posts/";
	private static const TYPE:String = BasecampResource.MESSAGE;
	
	/** @private **/
	public function MessageHelper()
	{
	}
	
	/** @private Mini-helper for doing path correctly */
	private static function categoryHelper(exten:String, 
	categoryId:String):String
	{
		return exten = !categoryId ? exten : "/cat/" + categoryId + exten;
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for creating a message.
	 * 
	 * <p>Typically, the XML provided is based on the template returned from
	 * a call to <code>prepare</code>.</p>
	 * 
	 * <p><code>title</code> is a required field in the XML, as is the 
	 * <code>project-id</code> identifying the project that is associated
	 * with the message. </p>
	 * 
	 * <p>Optionally, the message can contain flags for notifing team members
	 * of the posting of this message.</p>
	 * 
	 * <p>Also, the message can contain references to attachments that 
	 * were added in previous uses of the <code>AttachmentHelper</code>.</p>
	 * 
	 * @param content XML representing a category.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 * @see AttachmentHelper
	 */
	public static function create(content:XML):BasecampRequest
	{
		// remember that a 'message' is a create inside a request... 
		// Title is required or = we blow.
		// POST /projects/#{project_id}/posts.xml
		var projectId:String = content.post.child("project-id")[0];
		
		SharedOperations.nullEmptyAssert(projectId, 
		"content did not contain valid project-id", true);
		
		SharedOperations.nullEmptyAssert(content.post.child("title")[0],
		"Message REQUIRES a valid title", true);
		
		return new BasecampRequest("/projects/" + projectId + "/posts.xml",
		URLRequestMethod.POST, TYPE, BasecampOperation.CREATE, content);
	}
	
	
	/**
	 * Builds a <code>BasecampRequest</code> for deleting a message.
	 * 
	 * <p>The message and all associated comments are deleted.</p>
	 * 
	 * @param id The id of the message to be deleted.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function destroy(id:String):BasecampRequest
	{
		return SharedOperations.destroy(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for getting an existing message
	 * from the store.
	 * 
	 * <p>The XML returned is pre-filled with the existing values of 
	 * the identified message, and is ready to be resubmitted via the 
	 * <code>update</code> function.</p>
	 * 
	 * @param id The id of the message to be retrieved.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function edit(id:String):BasecampRequest
	{
		return SharedOperations.edit(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a list of messages.
	 * 
	 * <p>By default (not including a <code>categoryId</code> and leaving 
	 * <code>archived</code> as <code>false</code>) the last 25 messages 
	 * are returned.</p>
	 * 
	 * <p>If <code>categoryId</code> is provided, the last 25 messages 
	 * retrieved are specific to the identified category.</p>
	 * 
	 * <p>In both cases (with <code>categoryId</code> and without), if
	 * <code>archived</code> is <code>true</code>, all messages are retrieved
	 * in abbreviated format.</p> 
	 * 
	 * @param projectId The id of the project from which messages are to be
	 * read.
	 * @param categoryId The id of the category used to scope the list.
	 * @param archived Set to <code>true</code> if all message should be
	 * listed.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function list(projectId:String, 
	categoryId:String = null, archived:Boolean = false):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		var prepath:String = archived ? "/posts/archive.xml" : "/posts.xml";
		
		var pathPart:String = categoryHelper(prepath, categoryId);
		
		// GET /projects/#{project_id}/posts/archive.xml
		// GET /projects/#{project_id}/cat/#{category_id}/posts/archive.xml
		
		// GET /projects/#{project_id}/posts.xml
		// GET /projects/#{project_id}/cat/#{category_id}/posts.xml
		
		return new BasecampRequest("/projects/" + projectId + pathPart, 
		URLRequestMethod.GET, TYPE,  BasecampOperation.LIST);
		
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for retrieving a template for a 
	 * new message.
	 * 
	 * <p>The template retrieved is used with <code>create</code> to 
	 * submit a new message.</p>
	 * 
	 * @param projectId The id of the project that is to be associated 
	 * with the message when submitted via a call to <code>create</code>.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function prepare(projectId:String):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		return SharedOperations.prepare(
		"/projects/" + projectId + PATH_HELPER + "new.xml", "project-id",
		projectId, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a single message.
	 * 
	 * @param id The id of the message to be read.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function read(id:String):BasecampRequest
	{
		return SharedOperations.read(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for updating an existing 
	 * message.
	 * 
	 * <p>Optionally, the XML can contain flags for notifying team members
	 * of changes to the message.</p>
	 * 
	 * <p>Additionally, attachments can be associated with the message, 
	 * however, the attachments must have been uploaded prior to 
	 * association.</p>
	 * 
	 * @param content The XML content of the new message.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>. 
	 */ 
	public static function update(content:XML):BasecampRequest
	{
		return SharedOperations.update(content, PATH_HELPER, TYPE);	
	}
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //